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NAME 

overview • overview of! 'up library routines 

SYNOPSIS 

cc } flu its] filename f ... ] -lpup 

nKSfRUTION 

Stanford's Pup library is intended to be a system-independent library for dealing with the Pup 
environment. Although anyone intending to use these routines should be familiar with the Pup 
protocols and data structures, a brief description of the protocol layering follows. 

Transport I ayer The lowest level of the library is technically not part of the Pup 

protocol system: rather, it provides a means of moving uninter- 
preted p:.ckels from one host to another over a single data link. 
Mxamples of such links are serial lines. Arpanet connections (as 
viewed from the Pup world), and I'thernet cables. The local 
operating system proddes some sort of communication with the 
interface hardware, and the transport laur uses this to provide a 
system-independent interface to the network. [Cur really, only an 
I'thernet layer is implemented, supporting both .vub and lOmb 
l ; .thernets.| 

Pup Packet I .aver The first true Pup level is concerned with moving Pup packets 

from host to host Jin the Pup world, all routing is done by gate- 
ways, so Pup transfers can he thought of as an end-ta-end service. | 
This lay or takes a data butl er and some connection information, 
and c hoses the propi-r encapsulation and t ran- port medium. In 
the Stanford Pup library, there is a data structure called a Pup- 
Chan ("Pup Channel") which hides the information about the 
underbing transport mechanism. Actions at this level include 
writing packets to. ami reading packets from, a PupChan. 

The follow ing layers arc parallel (more or less) in level: 

I JSP (IJjle Stream Protocol) MSP is used to create reliable, sequenced, full 'duplex streams of 

bytes between two processes. It is used to implement. Telnet, 
I I P, and Mail protocols. 



ITTP 



SKM A I 
HUGS 



Miscellaneous Services 



SO 

Xerox Pup documentation 



l-TTP is very simple lile transfer protocol used primarily for send- 
ing Pi csv- formal files to be printed, and for booHoading small 
systems. It is easier to implement than a liSP-based I 'TP, and 
thus is also useful for communicating with stone-age systems such 
as Sail. 

This is a collection of simple operations based on a single packet 
request/ack scheme. It supports such services as. limeof day. user 
authentication, mail-checking, etc. A similar system is used to 
implement internetwork routing. 



Would be obsolete if it didn't work so well. 
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NAMK 

aloo - convert ASCII to octal numbers 

SYNOPSIS 

fonjj atoo(nptr) 
char *nplr; 

cc files... -Ipup 
INSCRIPTION 

This function converts a string pointed to by nptr to octal representation. The first unrecognized 
character ends the string. 

Aloo recognizes an optional siring of labs and spaces, then a siring of octal digits. 

SKK ALSO 

scahlU), alolU) 

ft I If W 

There are no provisions for overllow. 
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NAME 

bmovc - block move a buffer 

SYNOPSIS 

bmo>T(src, (1st, leu) 
char *src; 
char *dst; 
int len; 

cc files ... -Ipup 
DESCRIPTION 

Bmovc is used to copy a block of data from one place lo another. It is coded in machine language 
on the Vax as one instruction, thus becoming quite efficient. A c language version exists for tran- 
sportation to other machines, although any machine with a block-move instruction warrants 
machine-coding for efficiency. 

AUTHOR 

Jeff Mogul 

SEK ALSO 

swabO), bstringO) 

BUGS 

The Vax machine-code version of bmovc only works on huMers up to 64k bytes long. This is 
suircicnt for most applications; if there is a chance that the holler might be longer, then bvopy (see 
bstrin&O)) must be used. I lov\ever, bmovc is faster for small hollers, by perhaps 20%. 
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NAME 

bytcorder — discussion of byte ordering and the I'up package 

SYNOPSIS 

//include < i )'i|)/|H]plil).ii> 

cc files ... -Ipup 

i>] :?;(!{ n» iiON 

Different machines order small objects wiihin larger ones in dilTerenl ways. The PI)!*-!! and the 
VAX-ll, for example, order bytes so that the least significant byte in a In-bil wort! has the lower 
address (i.e., has a lower index in an array of bytes), and they order words ".ilhin longwords (32-bit 
integers) so that the least significant v. cud in the lorn-word ha- the lower address. On the other 
hand, many other machines (Alios, DIXMOs, MOMNHV; (Sun>,). and IBM equipment) use the 
opposite order; the least significant byte in a word has an address higher than the most significant 
byte, and similarly lor words wiihin longwords. 

Since the Pup protocols were developed at Xerox, using. Altos and POP- Wish machines, the packets 
normally are arranged by the ordering natural on those machines. This ordering will thus be 
referred to as the "Standard Byte Ordering", or SI JO, while the PDP-11 ordering will be referred to 
a* the "Non -Standard Byte Ordering", or NSBO. 

The Pup package is designed to compile and run on either sort of machine (actually, it would 
almost certainly not work on a machine whose data objects were not multiples of 8 bits long.) This 
is achieved with some pain, but most of the work has been hidden for you. 

The Pup library and the related header files are eonditioualli/ed on the type of machine you arc 
using: you must define to the C compiler a symbol indicating which machine you are compiling 
for; e.g., 

cc -DYAX foo.c -Ipup 

will work on the VAX (note that the Pup library must be recompiled for each machine; however, 
each C compiler will presumably look for object libraries in the right place.) The allowable 
machine names are: VAX. PDP_.11, anil M('68tM)0. You may also simply define PUPJSBO or 
PUP_NSBO to indicate the kind of ordering in use. If one of these names is not defined, then a 
VAX is assumed. 

Packets contain arrays of bytes; therefore, the following points arise: ■ 

words reading/writing a short word in a buficr involves bytcswapping the two 

bytes ill* the host machine is NSIK), 

long words read/writing a long word involves swapping the low and high short words 

(and the bytes wi thing them) iff the host machine is NSBO. 

byte arrays Are order-independent. 

If you follow the following rules, you will not go far wrong. Always: 

retrieve longs from butters using getlongO 

make longs for insertion into buffers using makclongO 

retrieve shorts f ront bullets using getshortO 

make shorts for insertion into butters using makeshortO 

Shorts, longs, a«d character strings sfomU always begin on a word boun- 
dary, that is, at an even byte address in a Puo daia butter. Phis is because 
some systems (such as Altos) often have hardwajie memory addressing res- 
trictions, GetshortO, makesliortO, getlongO, and makelongO are described 
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in pupnu'sc(O). 

AUTHORS 

John Scamons, JcfF Mogul, Dan Kolkovvit/, Bill Nowicki 

SEE ALSO 

pupmisc(9), pupstiing(9) 

DIAGNOSTICS 

cl lpl !'l mrtpacp dniiscdt chA tl!o 

BUGS 

I3CPL strings violate the rule about strings beginning on a word boundary, in that their stringy 
parts sort of don't. Get BC PI. siring and Put BC 7V. siring (see pupstring{9)) take care of this, though. 
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INAlMK 

checksum ••■ compute Pup-stylo checksum 

SYNOPSIS 

unsigned short vlrveksuHKbulTt'r.h'n) 
unsigned short *hulTer; 
int \m\ 

cc liles ... -Ipup 
\)VS< iiwvum 

( Inrksum calculates a Pup-style checksum o\cr a bullcr. The huller is considered to consist of 
unsigned shorts (Id bits each.) The length parameter is, however the length of the huller in bytes 
(since this is more usually available.) Odd Iciwihs are rounded down. 

The checksum algorithm is: start with 0, and repealedh (add in the next huller word using one's 
complement arithmetic, then Jo a Id bit rotate on the re-.ull.) II' the linal rciill is "- 0", replace it 
with 0. 

This routine is coded both in (.', and in machine code. On the VAX, the machine code version 
takes about 1 millisecond lor a maximal Pup packet. 

AUTHOR 

Jell' Mogul 

bugs 

Someone should write a routine thai recalculates the checksum Tor a modi lied bullcr. 
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NAME 

cftp -- Pup K1TP package 

SYNOPSIS 

# include <|)up/ofl|).li> 

ft include <pup/piipslalus.li> 

KfRocOpi. , ij(Kfcluin,St , JHi<. , r,tiiuconl,l)s«:ip) 
struct KitpChaii *Kfclian; 
struct Port *Scndcr; 
hit timeout; 
in i bsnap; 

!'J!\i'cOi)iMiS(l'Tch;ui,SiMiflcr,tiincout,l>sVfap,sockct) 
Socket socket; 

!:{'RecPc!;l(i:rchan,hur,!)uneii) 
cliar *buf; 
int +bullcn; 

ITttecKndUTVhan) 

I'.iSenu()peii(Krchan.l)est,tinicout,l>s\vap) 
struct Port *l)est; 

r.lKciHl()pcnS{Kfclian,l)c.sl,tiineoulJ)swa|),sockct) 

i:iSiMu!jVkt(i:fcliau,bur,lH«nen) 

l'!ISem)!'n<l(l\fclian) 

l-ISciuiCloscd-rchaii) 

r.llpKc:i(Hrfclian,l)ul',t)ullcii,rlHineii) 
int *rluillen; 

I ripWiite(i:rcliau,l)uf,l)ullcn) 

cc files .... -Ipup 
1)I.S( IMP UGN 

The routines described in this manual entry constitute .1 fairly complete set of functions for imple- 
menting 1 11 I I' transfers. They are b;ised on the Pup l ibrary, and thus can be used without regard 
to underlying transport medium. 

All oC the routines refer to structure called an /:*///>( '//<///, which describes the slate of an I'll "IP 
transfer. A user should do nothing to an ITtpChan except, allocate space for it, ;md pass it to the 
routines in the package. Space should not be deallocated until the ITtpChan has been properly 
closed. An IT'TP transfer is unidirectional; one is either sending or receiving a file, but not both. 

There are two levels of data transfer routines. The higher level, using KftpWrite, involves sending 
an entire file as one bulfer (i.e.. the calling, program need not worry about packet disassembly). This 
works well on a virtual memory system, but can exceed the memory capacity of a smaller system, 
so the packet-level routine i'JXciuU'ckt is provided as well, b'or receive transfers, one may use 
cither l jipReuil or l\/Rvc/\'kl\ ITtpRead provides a slightly simpler interlace than ITKccPckt. 
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These three routines provide i\ liable transport of single packets, but the user --prog ram must assem- 
ble or disassemble the file accordingly. 

An IT IT lile read transfer follows die following general sequence: ihe PUpChan is created using 
i'lUt cOpvn. Ihe lile is received using PlipRcad or TTRecTckt, and the l!f'tp(. h.in is closed using 
i-Jlicvl-ml. 

An Mb TP lile write transfer follows ihe follow in.' general sequence: the ITtpChan is created using 
f '/SriidOpcn. the lile is sent using ITlpWrite or I'lSendPckt, i.jSnulF.iul is used to indicate that the 
end of lile has been reached, and the ITtpChan is closed using i'.jSnuU "lose. 

m wnsov koutinfs 

These routines return OK on success unless noted otherwise. 



MKecOpcn 



i'.IKecOpenS 



TReclVkl 



l-fRccl-iKl 



l-'ISendOpen 



PfNendOpcnS 



KfSendPckt 



This opens an Id- I P channel in preparation lor receiving a lile; the 
Sender Port structure is" used to indicate ihe address cf the desired sender. 
If this ha-, both net and host lields set to .cro, then the lirsl incoming lile 
w ill be received, idepeudent of the sending host. I he limi-mit parameter is 
the channel timeout in seconds; if h.uitrp is true, then bytes will he taken 
from the net swapped from Network Standard' b\le order if PTlpRead is 
us'\l. (See h\icon/ci( { ))). This loutinc can return NOC1IAN or 
NOROUTIi. 

This is exactly the same as PfRecOpcn. except that it allows you to specify 
the socket to receive on (otherwise, the standard ITTP socket is used.) 

This routine is used to received a packet from the net. The returned bulfer 
can be up to M AXPUPI ).\ TA I T'N bytes long; the length is returned in 
hujlcn. IK le order considerations are ignored. I T I P I NI )OI *ll T is 
returned upon sueessfullv rccebimi the end of the file. I he possible 
failure codes are TIM I -(HIT. I TIP. R I -START. Ill P OUTOISYNCI I, 
PI I P I RROK, or Id I P.AItC)IM . On IT IP ABORT, the global I ff- 
pI'.rrMsv will contain a human-readable error message, and the global 
integer //////. l/w/C '<></<■ will contain the protocol-defined abort code. An 
Id- 1 P UPSTART humus that the p icket just received is really the fust of 
the lile, which is bring retransmitted; the caller of this routine should 
nunc the returned buller to the appropriate place and reset its various 
pointers. 

This releases resources used in a completed Id TP read. It returns 
IT TP J'RRQR if the ITtpChan wasn't open for receiving. 

This routine is used to create an ITtpChan for sending a lile. The Dest 
Purl structure is the address to which the file will be sent; the timeout and 
bsvvap parameters are as described before. On failure, NOCIIAN and 
NOROU I'i : can be returned. 

This is exactly the same as PlSendOpen, except that it allows you to 
specify the socket to send to (otherwise, the standard ITTP socket is 



KfSciiclKnd 



This routine is used to send a data packet; the maximum data length that 
it will send is ITTP>1AC_PACKI-T bytes. On failure, it can return 
TlMliOUT, ITTP.BAI >ACK, ITTIMvlvROR, or PTTP_ABOR T; upon 
an TITP_ ABORT, ITtpPrrMsg and I TlpAborlCode are set as described 
before. 

'This is used to indicate to the receiver that the end of file has been 
reached. No data is sent. 'The possible returns arc the same as with 
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NAMK 

(enarp) enlfhiibpuparp, ennoarp Address Resolution Protocol (A UP) routines 

SYNOPSIS 

// mcUttfc <[mjt/p«ii!ib.h> 
// ittctitclf <piip/pupst;itiK.h> 

oni()mlH«ip;up<rut>l lost, I hudvaiv! lost, lid, dvi paraim) 
Host * Pup Host ; 
diar *l I a nlv, a re Host; 
till fid; 

union DevParams *devpar;uns; 

t'iiru>arp<l*npl Josl, Nardvvarellost, lid, lU'vparams) 

cc tiles ... -Ipitp 
HVS( KIPTtON 

These routines pro\ ide a variety of Address RcM>tution Protocols (ARPs) lor use on ethernels. An 
ARP is used when the formats of the software host address and the hardware host address are so 
different that there is no simple mapping between them. 

1'nK^ubpitparp is used for resolving Pup addresses on the lOmb etheruet. i'.niu\irp is used when 
there is a simple mapping; ih.it is, "Alien hardware addresses are Hbil values, i.e., on the .>mb elher- 

net. 

The parameters to all routines in this group ale the same, so that they can he used by generic code. 
t'upittfst anil llanhvtirclhist arc the addresses of bulfei's for Pup .and hardware addresses, respec- 
tively, fill is the Unix file id on which the etheruet device is open (these routines may only be 
used 'with an . t! read \ -open device.) f)<vp t mtui.\ is the address of a device parameters structure 
returned by rmtpctiW). 

These routines provide three related operations: 

What's my Pup Host Number? If lltml\\\tivth>\t is NUM ., then the ARP routine returns the local 

Pup host number in hiplh >\L 

Pup Host to Hardware Host (men a Pup host number in the buffer refored to by Pupllost, 

returns the associate hardware host address in the Htinlmircllost 
butler. Ulnithwm llosl must be non-NUI.l.) 

Hardware Broadcast Address As ahove; if the buffer refered to by fttpllost is zero, returns the 

hardware broadcast address. 

AUTHOR 

Jefl' Mogul 

SKK ALSO 

cnopenP)), Kl ; 026 for a more flexible ARP. 

DIAGNOSTICS 

Returns OK if it worked, or ARPI-AH.URP: if it didn't. 

BUGS 

tl would be nice if there were a reverse mapping function (llarware host number to l\ip host 
number). 

f:'nl()mhpup<irp is not yet implemented! 
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KfSendPckt. 

ITSendClosc This releases resources used in a completed KITP write. Ii returns 

ITTP_.l'RROR if the ITtpChan wasn't open for sending. 

ITtpRead This is used to read a packet from the net, hut it has a cleaner interface 

than PTRccPekt. The parameter buflcn is used to indicate the maximum 
allowable size of the returned buller; rhujlm is used to return the number 
of bytes read (there is no indication of truncated huflers!) Ai end of file, 
IT IT.I jNDOI-MI.I- is returned. Possible failure codes are TIMKOUT, 
ITTI^OUTOI-SYNCII. and l-TTP ...b.RKOR. which are fatal, 
IT' TP.APOR T. which is fital but which returns information in ITl- 
. . pITrMsg and blip AborK ode. bin ally if l-l- I P WAI T is returned, the 

transfer has failed but may he restarted after waiting for a period given (in 
seconds) by the global I'.flpWailiinw. 

ITlpWrite This routine writes a huller of arbitrary length over an Id- TP channel. It 

ran be called moie than once: the final call must be followed by a call to 
PlSendl-nd. The possible failure returns are TIM I -01 i f. Id TPJ-K KOK, 
IT'TP AllOKT. I .i I P.. WAI I , and Id - I P, K 'I -START. If Id- I P AIJORT 
is returned, appropriate information is available in I Tlpl 'n Msg and ITtpA- 
boilC'odc. If I I IP_WAN is returned, the caller should wail for several 
seconds, then start from scratch. If IT I T_K I'.SI Al< I is returned, the 
caller should restart from scratch but does not have lo wait. 

SKK ALSO 

eftp( 1 ), pupporl(9) 



Note that the clip command does not use this implementation of T 

DIAGNOSTICS 

The possible values for ITtpAbortCode are: 



KUCiS 



l-l- I PA I X rSI-.NI)l ; .K 

i-ttpa i-xi ri-ct:ivi;r 

l-TTPA RI-X'IUISY 
l-l- TPA pi H'OI'SYNCI I 
l-T'TPAJVIISC 
l-TTPA IONGWAIT 
I T I PA_MI-;i)\VAI T 

id tpa_suspri:q 



Pxternal Sender Abort 
I External Receiver Abort 
Receiver busy Abort 
Out of Synch Abort 
Misc Abort 
Long Wail Abort 
Medium Wail Abort 
Suspend Request Abort 



A routine to send an ITtpAbort is needed. 

I Tip Read might be redone to handle packet assembly. 

A function is needed to determine the actual sender of a file if the Sender was not specified when 
calling ITUccOpcn. 

It should be easier to override the assumption that the KITP receiver is always on socket 020; this 
would be useful for bootstrap loaders. 
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NAM 15 

(cnolliltcr) ensetfilt, efinit, cfwdinsert, cllginscrt, efchinsert, cfANI) - build cthcrnct Hirers 

SYNOPSIS 

7/ include <pup/puplib.h> 
# include <pup/pupstatus.h> 

ensctfi!t(lid, enfilt) 
int lid; 

struct enctfilter *cnlill; 

diniUdevparams, cnliit, priority, packctlype) 
union Devi drains *dcvparams; 
unsigned char priority; 
unsigned short packet type; 

ebnlinsnUdevparains, en lilt , olTset, value) 
int offset; 

unsigned short value; 

ell»insert(devparanis, cnlilt, offset, value) 
unsigned long value; 

elVfmisert(devparains, cnlilt, oltset, value) 
unsigned char value; 

efVNI){enfilt) 

cc files ... -Ipup 
DESCRIPTION 

This is a collection of routines to make building cthcrnct packet I liters (sec enet(t)) relatively pain- 
less. 

cn.sc/Jilt lakes an enetliller structure and makes it the applicable lil ter for the elhernet device open 
on Jid, using device parameters devpamms, both of which should have been obtained from eno- 

I'.Jinit takes an enelfilter structure and initializes it to an empty filter, with the given priority. ( The 
lilter is "empty*' except that it specifies which paekettype is to be accepted. If paekettype is zero, 
then all packet types will be accepted.) 

I'j'wdinscrt, eflyjnsert. and e/eli insert add equality tests for unsigned shorts, longs, and chars to a 
filler. The offset parameter is in units of bytes, starling from the dala part of an elhernet packet. If 
you want to filler on cthcrnct packet header liclds. you must use a negative offset. 

i'.J'ANI) adds a logical conjunction operation to the lilter; if you put // terms into a lilter, you 
should put // --■ / ANDs in afterwards to result in one boolean value for the lot of them. 

bikers have maximum sizes; the current maximum is big enough for sane users, and the bigger the 
lilter, the slower things go. 

AUTHORS 

JcIV Mogul 

SKK ALSO 

enopen(9), pupsetfiltcK 0 ), pupsektliU(9)", enet(4) 
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llcunns OK if ttiiugs work, ttetuiiis Ml U K t (K>BIG if the next operation would make the filter 
st i ncline overflow. 

BUGS 

It might l>e «ice to have other logical operations available. 
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NAME 

cn Flush - flush an cthcrnct input file 

SYNOPSIS 

# include <pup/pupslatus.h> 

cnfltish((i(l) 
int lid; 

ce files ... -Ipup 
DESCRIPTION 

Enjlush is used .to remove any packets that may be available to be read from the queue for an et.li- 
crnet minor device. The argument should be a Unix file id of an cthcrnct device. 

To avoid an infinite loop, the filter set for the cthcrnct device should reject all packets, so that no 
new packets arrive while the queue is being Hushed. The filler that is set when an cthcrnct device 
is opened is such a filler. 

The enjlush routine sets the timeout delay for the cthcrnct device so that it returns immediately if 
no input is available; the routine does not restore the previous limeoul delay. This may be con- 
sidered a bug by some, although this routine is usually called just once, right after the file is 
opened. 

AUTHOR 

Jeff Mogul 

sit: also 

enopen(')), enct(ilter(9) 

DIAGNOSTICS 

None; this routine always returns OK. 
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NAME 

cngclhost - determine Pup host number of elhernet interface 

SYNOPSIS 

cnt»ethost(lid, AKP) 
int lid; 

in (*ARP)<); 
ce files ... -Ipup 

descmption 

/'Jigcfhosl is passed the Unix file id (as returned by cm>pcn{V)), of an elhernet file, and a pointer to 
the appropriate address resolution protocol < AK I*) aniline (see r//i //•/>( 9)), and returns the Pup host 
number of the local machine, as found on the elhernet interface which is open on the given file id. 

Note that any given machine may be connected to several networks, and may have different host 
numbers on each network. 

AUTHORS 

John Seamons, Jelf Mogul, Dan Kolkowilz 

SKK ALSO 

em>pcn(9) 

BUGS 

This is a nasty layer-crossing. We could use a routine to return the actual hardware address of the 
interface, simpler to use than the l-NIOC I )liVP ioctl (see vncl( \).) 
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NAME 

enopen - open an ethernet file 

SYNOPSIS 

# include <pup/pii|)lil).h> 

cnopcudlcvnamc, devparams) 

char *(k'viuimc; 

union DcvParains *devparams; 

CC (lies ... -11)111) 

DKSCRIPnON • . , 

Knopen attempts to open one of the clhcrnct minor devices available on the specified interface, 
l-.g., if devmmw is "/dev/cnetA", then it will try to open "/dev/enetAO", "/dev/enetAl", etc. (t 
then sets ;i packet filter (see cncf(<f) ) for the device which ignores all packets. Hushes any pending 
input packets, ami returns the Unix lile id of the ethernet device. It also returns a device parame- 
ters structure in tlcvpimims, for use with other Pup library routines at this level. The device param- 
eters include such things as hardware address formats, addresses, maximum packet si/.e, etc. 

There is no corresponding enclose routine: use the normal elose(J) system call. 

AUTHORS 

John Scamons, Jeff Mogul 

SKK ALSO 

close(9), cnet(4) 

DIAGNOSTICS. 

Returns -- 1 if no ethernet minor devices are free. 
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NAME 

on read — read a packet from art ethernet file 

SYNOPSIS 

# indufte <pnp/pnplib.lt> 
U include <|Hip/i)tippaeket-li> 
It iuclinfe <j«!j)/j)t2j)s(atiis.li> 

enreadCfolv ck^paranrs, packet, frHcr, tiivicoutl 
hit tut; 

union t>e*Params *ftev|KiTatiis; 
struct f.n ticket *paeket; 
stnut eiictliltvr * filter; 
nit timeout; 

emea<lt|uick(r«l, thvparams, packet) 

cc files ... -tpup 
DESCRIPTION 

Knrcad is used to read one packet from an ethernet minor device. The jut parameter is the Unix 
tile id of (he device to read from, dcxpanuns is the tlevice parameters structure returned by eno- 
/><'//(')), Jiih r is an ethernet packet filter (see cnei(-l) ) to he set tor the device, and limetmt is the 
time (in duck ticks, 1/60 of a second) to \vait before returni ng em pi y -I ki nded. 

Packet is the address of the tup field of* a NclPnekcl structure where the received packet will be 
put. The caller must allocated space tor the entire netpackct. but must pass the address of the data 
part of the packet: this makes ii possible for the caller to use this routine without knowing how 
large the ethernet header is. l or example: 
struct Net Packet phuf; 

status = eureadCfid, &devparams, &(pbuf.Hip>, &filtet\ t'nitcoot); 

If I lie value Nil} J. Is passed for the filter address parameter, no new Biter is set. This means that 
whatever previously set Biter exists will be used 

/•Jirctidtftifck works the same as enread, except that it does not take fitter or timemtt parameters; if 
these arc already set, then the cost of passing them can be avoided. 

AUTHORS 

John Seamons, Jeff Mogul 

SEE ALSO 

enopcnOJ), emvritc<9) 

DfAGNOSIKS 

Returns TIMHOUT if the read tails (for any reason, including such things as file not open; etc.),. 
otherwise returns OK. 
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NAME 

ensctbacklog - set ethcrnet input queue baeklog 

SYNOPSIS 

ensetbacklog(ful, backlog) 

hit fid; 

int backlog; 

cc files ... -lpup 
DESCRIPTION 

Ensctbacklog is used to set the input queue baeklog (the maximum number of received paekets that 
will be queued pending a read) for the ethcrnet minor device denoted by the fid parameter. Back- 
log specifies the maximum queue length; if backlog is zero, a default" value will "be used, and if it is 
higher than the maximum allowable value, the maximum will be used. 

AUTHOR 

Jclfrcy Mogul 

' ALSO 

onopcn(9), cnct(4) 
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NAME 

cnsignal - enable or disable signal on cthernct packet arrival 

SYNOPSIS 

// include <s)s/si«niil.h> 

cnsi]*naKfid, signum) 
in I lid; 
int signum; 

cc files ... -Ipup 
DKSCKiPliON . 

i'.nsiy y nal is used to specify a Unix signal u> be delivered when a packet arrives for the cthernct 
minor device denoted by the .//>/ parameter. Signum is the signal number; it is wise to choose one 
thai is otherwise unlikely to occur. 

Once the signal has been set, it Will be delivered each time a packet arrives (even if the packet is 
discarded by the cthernct driver because ti e input queue is full.) To disable the signal, call cnsig- 
nal w ith a ' signuin of zero. 

The idea is that the calling program has set up a routine to catch the specified signal and then read 
a packet from the cthernct. 

AUTHOR 

Jeffrey Mogul 

sit; also 

cnopen(9), cnread(9), pupiiitO), signalO), sigvec(2) 

DIAGNOSTICS 
None. 

BUGS 

Writing code to handle signals properly is a black art. It is far safer to use sclccfd) when possible. 
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NAME 

enwrite - write a packet to the cthcrnct 

SYNOPSIS 

# include <()iip/puplib.h> 

# include <pup/puppacket.h> 

# include <pup/pupstatus.li> 

cmvrilc(I)st!*ost, Ptype, fid, devpamms, packet, len) 
char *I>stl lost; 
unsigned short Ptype; 
int fid; 

union DevParams *dcvpurams; 
struct Kn Packet *packet; 
int leu ; 

cc files ... -Ipup 
DESCRIPTION 

limvritc is used to write a packet onto the ethernet. The butter refercd to by Dstllost is tlie 
hardware address of the immediate destination host; Ptype is the Ethernet packet type (not the Pup 
packet type) to be inserted into the packet; fid is the Unix file id of the ethernet device and 
devpamms the device parameters structure, both returned by enopenp)). 

Packet is the address of the /'///; fir \ a NctPackcl structure where the encapsulated data has 
been put. The caller must allocated ■ for the entire nctpackct, but must pass the address of the 
data part of the packet: rnwritc will '.met the ethernet header. This makes it possible for the 
caller to use this routine without know. . how large the ethernet header is. h'or example: 
struct NctPacket pbuf; 



status ~ enwrilc(& l)sll lost, fid, &devparams, &(pbuf.Pup), length); 
/.en is the length of the encapsulated pari of the packet, i.e., not including the ethernet header. The 
length of the encapsulated packet should be an even number. 

AUTHORS 

John Seamons, Jell* Mogul, Dan Kolkowitz 

SEE ALSO 

cnread(9), cnopen(9) 

DIAGNOSTICS 

If the devparams structure is invalid, returns PCNO TOPP'N (a poor choice of codes). Otherwise, 
always returns OK. 
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naaik 

maddtoname translate a Pup Port address U) a name 

SYNOPSIS 

// include <j)up/|niplil>.h> 

tt include <j)U|»/impcon.staH(s.lt> 

// include <|> ti|>/pu{>sl itttis .tt> 

ma d d 1 omimc{ \ » e«i l*o rl:,j nun c) 
stunt Port *RemPt>rt; 
ehar '*ttnmc; 

ee Dies ... -Iptip 
DKSCKIPilOIN 

MiMhrnamv is used to translate a Pup Net/ 1 lost/Socket identifier fa /W//* into a string name. This 
is done by making a request to the Mrxefonk'es. server on the local net (the request is broadcast to 
all hosts.) 

The input parameter is a Port, which inchules the net number, the host number, and the socket 
number of live desired name. Any of these can be zero, and the name server will interpret this as it 
pleases. The returned string is of the form "I lost Name -I SockeiName", or just '1 lost Name" if the 
socket is zero. The value OK is returned on a successful translation. 

AUTHOR 

Jell i cy Mogul 

sit: also 

mlookupf 1 )) 

DIAGNOSTICS . 

There are several possible error returns: 

NOCI IAN means that no Pup channel was available. 

TIMI-OUT means that the server did not respond within a reasonable timeout period. 

NO H OUND indicates the specified Net/I lost/Socket was not found. The returned string name 
contains a lutman-readahle error message. 

BUGS 

The function assumes that the server host is one which is on the local network, anil that it is accept- 
ing broadcast packets. Both assumptions are reasonable. 



7lh I Edition 



1 



MAITRIIHJTI«S(9) 



UNIX Programmer's Manual 



MATTRIBUTi;S(9) 



NAMK 

matlributcs - get Pup Network Directory entry attributes for an address 

SYNOPSIS 

4t include <pu|)/|)iiplib.h> 

// include <pup/pupconstants.h> 

// include <pup/pupstatus.h> 

matt iibuli's(RemPoi1,at tributes) 
struct Port *RemPort; 
char *aUril)utcs; 

ce files ... -Ipup " ' 

l)F.S( RIPTION 

M attributes is used to gel the "attributes" associated with the network directory entry for a Pup 
Net/I lost/Socket identifier (a Port) into a string attributes. This is done by making a request to the 
MiscScniccs server on the local net (the request is broadcast to all hosts.) 

The input parameter is a Port, which includes the net number, the host number, and the socket 
number of the desired site. Any of these can be /.cm, and the name server will interpret this as it 
pleases. (However, this is most likely to succeed if the Port denotes a specific host.) The returned 
string is of the form 

AllributeName: AtlributeValue [ AuribuleNamc: Attribute Value ... | 

That is. it gives the name and value of one or more attributes for the specified host. (Actually, if 
there are no attributes, the string will be empty.) The most likely attributes are "Location" and 
"Owner". Thus, this can be used to find the supposed location of a host. 

OK is returned if the call is successful. 

AUTHOR 

Jellrey Mogul 

si:i-; ALSO 

mlookupO), maddtoname(9) 

DIAGNOSTICS 

There are several possible error returns: 

NOG IAN means that no Pup channel was available. 

TIMI'OUT means that the server did not respond within a reasonable timeout period. 

NO ITOUN I) indicates the specified Nel/I lost/Socket was not found. The returned string attri- 
bulvs contains a human-readable error message. 

RUGS 

This protocol is peculiar to Stanford. 

It is also pretty dumb; there is no convention for delimiting attributes, and there is no way of 
guaranteeing that any given attribute will be returned. Also, if the list of attributes won't (it in a 
packet, things will probably not work well. 

PROTOCOL 

I 'or lack of a better place, the protocol is documented here. 

Request I'ormat The PupTypc is A IT'RIIHJTI-SRI-Q (0.U0) and the data portion 
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Reply l ; orm'at 



is the Pori. 

The PupType is ATJ'RIItU TIISRRP ((Mil) and the data portion 
is the aUrii>ule siring. Hrrors are indicated by PupType I.OOK- 
UIM-RR (Name Lookup I 'nor), with a human -readable explana- 
tion string in the data portion. 
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NAME 

mbootdir - get a boot file directory from a boot server 

SYNOPSIS 

# include <pup/puplib.h> 

// include <|)U])/pupconstunts.li> 

# include <pup/piipstatus.h> 

nibootdir(Ser\erPort, bulTer, I) u lien) 
struct Port *ServerPort; 
char *buiTcr; 
int *buflcn 

cc files ... -Ipup 
DESCRIPTION 

MhooUiir is used to request (from the boot file server whose address is in ServcrPort) a list of the 
availble boot files. What is returned is a buffer full of entries that may be larger than the maximum 
size of a pup\ V/jrlcngthn/lhe the reference parameter bullen. In order to gel this (almost) right, the 
routine may take a fair amount of lime (on the order of 3 seconds) to get a boot file. 

The structure of each entry in the returned buffer is: a short word giving the "boot file number", 
two shorts giving an Alto format date (low-order word fust), and a boot file name in IJCPI. string 
format (see pupstrin^))). 

The ServcrPort may be a broadcast address. 

AUTHOR 

J elf rey Mogul 

SEE ALSO 

mboolrcq( ( )), pupslring(9) 

DIAGNOSTICS 

I here are several possible error returns: 

NOG IAN means that no Pup channel was available. 

TIM I 'OUT means that the server did not respond within a reasonable time. 

BUGS 

The protocol used involves sending one request packet, then awaiting one or more reply packets. 
There seems to be no way to gel this right short of some hairy timeout hackery, so the routine may 
occasionally return a partial directory. The user should try again if things don't look right. 
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NAME 

nVhuolreipesi - • revest a tK%o|-l«3s.«d 

SYNOPSIS 

# include <pjji/fiup1ikh> 

// iMi'iu'jk 1 <i»aii§/j>iij)C4Wisla«ts.Sj> 

# include <35iip/|Hij;si;Uus.li> 

niton nqurslf I Ki Port. RoolSorL, BFNnniber) 
sUuei r«rt *lSstl»ort; 
unsigned lung ISoalSoek; 
unsi^nef! Ion*; lltfNuiiifor; 

i)i scini'i join 

MhHmquesi is iiscd l« request dual a hoot server, desigiKUcci by ihtPart, send a file via the Alto 
Ix^otstraji protocol, which is diicuinented elsewhere. Ilie H*miSm k parameter is sent to the server 
to indicate what picket on die local host is to receive the Ixkh" lite. Ilie UfKmnbcr is sent to the 
server to indicate die lltscH File Nundtcr which is requested. 

Only one attempt is made, and no acknovJedi*eine«t is expected. Ilie bootstrap louder should 
retry this function if no file arrives within a rcaMniable'iiMicout. lite normal return value is OK. 

AUTHOR 

.leifrey Mogul 

SKI , A3 SO 

ui^nilxMHreqC 4 )) 

MOC11AN is returned if no i*np channels are available. 
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NAMK 

mkissofdcath - send a KissOfl)calh Pup 

SYNOPSIS 

# include <pup/puplih.h> 

# include <pup/pupconsl:ints.li> 

# include <pup/pupstatus.li> 

nikissofdeatiiOXstPort, DI'upID) 
struct Port *l)stPort; 
unsigned long DPupll); 

DESCRIPTION 

MkissojUcalh is used to send a KissOlDeath packet to the specified port. The Pupil) of the packet 
is the one specified by the caller. Only one attempt is made, and no acknowledgement is expected. 
The normal return value is OK. 

AUTHOR 

Jeffrey Mogul 

SEK ALSO 

nuscservcr(9) 

DIAGNOSTICS 

NOG IAN is returned if no Pup channels arc available. 
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NAMK 

m'ookup — translate a name to a Pup address 

SYNOPSIS 

// include <piip/ptiplil>.h> 

// include <pup/pupcon.st:iiits.h> 

// include <pup/pupslatus.li> 

iiilookupduinie.Kel Port) 
char *nanie* 
struct Port *KctPort; 

cc files ... -Ipiip 
!)!<>* MPTION 

Mlookup is used to translate a siring name into a Pup Net/1 lost/Socket identifier. This is done by 
making a request to the MiM'Scwicvs server on the local net (the request is broadcast to all hosts.) 

The input parameter is a string which is to be translated into a numeric identities It can either be 
of the form "MoslName I- Socket Name", or of the form "MoslName", in which case the returned 
socket will be zero. The output parameter is the Port address of the named entity. This is passed 
back to the caller, so the actual parameter is an address. The function value OK is returned on a 
successful lookup. 

AUTHOR 

Jeffrey Mogul & John Seamons 

sit: ALSO 

maddlonamep)), port(9), puperrmsg(9) 

DIAGNOSTICS . 

There are several possible error returns: 

NOCIIAN means that no Pup channel was available. 

TIMI-OUT means that the server did not respond within a reasonable time. 

NOTIOUNI) indicates the specified name was not found. The (global) returned string 
PupKrrMsj; contains a human-readable error message. 

The function assumes that the server host is one which is on the local network, and that it is accept- 
ing broadcast packets. Iloth assumptions are reasonable. 

When translating an octal host number of the form ".WO", the function returns "()// 300 //()". This 
is intuitively right, but wrong according to Xerox software. (On the other hand, it parses 
"50// .100" as "0// 50 /MOO"; i.e., the assumption is that #'s appear starling on the right.) 



7th Iklition 



1 



MMA1LCHI<CK(9) 



UNIX Programmer's Manual 



MMAILCHKCK(9) 



NAME 

mmailchcck — find out if a user has new mail at a Pup host 

SYNOPSIS 

# include <pup/puplib.h> 

// include <pup/pupeonstants.h> 

ft include <pup/pupslatus.li> 

nunailclucM UemPort, UseriNaiiie, message) 
struct Porl *Reml > ort; 
char *liscrNamc; 
char "message; 

DKSCRIP HON 

MnuiHclurk is used lo find out if a given user has new (unread) mail waiting at a given host. This 
is done by making a MailClwck request to the MiscScnkcs server at the specified host. 
(Specifically, a "I aurel-style Mail Check Request" is made.) 

The input parameters arc the address of the host (the socket field is ignored; mail check requests 
are always sent to the MiseServiccs socket) and the username (actually, mailbox name) UscrNainc. 
The host and net numbers can be zero, and the request will be broadcast to all hosts - only the 
first answer will be returned. The following non-error return codes are possible: 

NKWMAIL indicates that new mail exists; there may be a human-readable explanation in mes- 
sage. 

NONl-AViYIAH . indicates that no new mail exists; a human-readable explanation is in message. 

NOSUCI IMIiOX indicates that no mailbox with the given name exists at the host; a 

human-readable explanation is in message. 

The parameter AY////V// is passed by reference to allow mmailvhcck to return the address of the 
host that actually responded, in the ease of a broadcast request. The calling. program can then use 
nhnlilloininic( l >) to determine the name of the responding host. 

AUTHOR 

Jclfrey Mogul 

SKK ALSO 

mIookup(9), maddtoname(9), mailchcck(l) 

DIAGNOSTICS 

There arc several possible error returns: 

NOG IAN means that no Pup channels were avaiable. 

TIMKOUT means that the server did not respond within a reasonable period. 
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NAME 

msesrvrcq - make a MiscScrviccs request 

SYNOPSIS 

# include <ptip/pu|)lil>.h> 

// include <|)(ij)/pii|)constan(s.li> 

// include <|)ii|>/pii|>slatiis.li> 

mscsrvrc(|( Rom Port, Inltuf, liiRun.cn. OutBuf, OuliUifLcn, ReqTjpe, Timeout) 

struct Port * Rem Port; 

char *lnlUif; 

int InRufLcii; 

char OutBuf; 

int *OutBufl.cii; 

unsigned cliar Re<| Tvpe; 

in ( Timeout; 

cc files ... -Ipup 
DESCRIPTION 

Msesrvrcq is a routine meant to be the core of most requests to a Miscellaneous Services server. 
The caller sets up a buller to send to the server, described by ///#«/' and lnlhifl.cn. and a Port 
structure ( RcmPorl) that gives the host/net address of the server to use (using the address ()//()//' 
will cause the request to be broadcast on the local not.) The caller also passes (in Rcql'ypc) the Pup 
Type of the request (e.g., M All. CI HICK, ATIMI\IU\Q, etc.). and the number of seconds to wait 
before timeout. , 

The Junction returns the Pup Type of the reply received, and uses Ouiliufio store the reply buller, 
and Out liujhcn to store the length of the reply buller. The true host/net address of the responding 
server is returned in Rcml*orl. 

AUTHORS 

John Seamons, Jeir Mogul 

SICK ALSO 

pupporl(9) 

DIAGNOSTICS 

Returns TIMKOUT if the request timed out; returns NOG IAN if there were no available Pup 
channels. 

BUGS 

The manner of signalling error on return succeeds only because TIMHOUT and NOCHAN arc dis- 
tinct from the possible MiscScrviccs Pup types. This is a lousy way to code (sorry.) 
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NAME 

msendumsg - send a message to one or all users at a Pup host 

SYNOPSIS 

# include <pup/puplib.h> 

# include <pup/piipconstaiUs.h> 

# include <pu|)/pupstalus.h> 

mscmlunisgtScndcrNunic, RcccivcrName, message, RemPort); 
char *SenderNaine; 
char *RcceiverNamc; 
char *inessagc; 
struct Port *RemPort; 

cc files ... -Ipup 
DESCRIPTION 

Mseikhunsg is used to send a short message (no more than 501) characters) to a user, or all users, 
logged in at a host on a Pup network. The remote host must be running the Stanford Misc Services 
server. 

The protocol is a connectionless one (one packet per message), so only as many bytes as will fit into 
one Pup packet may be sent. The message is sent with a Pup type of SPNDUMSG; the Pup Data 
portion of the packet contains the single null-terminated string 
"ScndcrNamc:ReccivcrName:mcssage"; the message has new-lines embedded. If the Receiver- 
Name field is '*', then the server at the receiving host delivers the message to all logged-in users. 

The address of the receiving host is designated by Rcmport. The value SI-NDUACK is returned if 
the remote host received and delivered the message. If the host address is zero, then all hosts will 
receive the message; the function will only keep retrying until it receives one response, so delivery 
is only "guaranteed" to one host. (Actually, it is not guaranteed at all.) 

AUTHOR 

Jeffrey Mogul 

SKK ALSO 

miscservci (9), send( 1 ) 

DIAGNOSTICS 

There are several possible error returns: 

NOCTIAN means that no Pup channel was available. 

TIM POUT means that the server did not respond within a reasonable period. 

SPNDUPRR means that the remote host responded but did not accept the message, either 
because the user was not logged in, or because the host did not grant permission. 

lUJGS 

The protocol used is peculiar to the Stanford implementation of Pup. 

The message may be delivered more than once (there is a race in the timeout logic.) 

I haven't implemented this one yet. 
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NAME 

msunbootreq - request a boot-load 

SYNOPSIS 

# include <iiui>/puplib.h> 

7/ include <pup/ptipvon.stanls.h> 

// include <pup/pups1atus.h> 

nisiiut>ootrc<|(I>stl\>rt, BootSock, KPNumber, Bh'Natnc) 
struct Port * I tot Port; 
unsigned long KootSock; 
unsigned long IM Number; 
char *IJI'Naiue; 

cc files ... -Ipup 
DKSC RIP HON 

Msunbootreq is used to request that a boot server, designated by DslPort, send a file via the Sun 
bootstrap protocol, which is documented in /usr/sun/doe/sunbool/Sunlioot.press. The JtootSock 
parameter is sent to (he server to indicate what socket on the local host is to receive the boot file. 
'I he H /Number is sent to the server to indicate the Bool I 'lle Number which is requested. How- 
ever, if the Hl'Name parameter points to a non-null string, then the boot server will ignore the 
number given, and return the named file (the name must be meaningful to the server's host.) 

Only one attempt is made, and no acknowledgement is expected. The bootstrap loader should 
retry this function if no file arrives within a reasonable timeout. The normal return value is OK. 

AUTHOR 

Jeffrey Mogul 

SKK ALSO 

iuboolrcquesl(9) 

DIAGNOSTICS 

NOCIIAN is returned if no Pup channels arc available. 
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NAME 

nitimcchcck — get time from a Pup server 

SYNOPSIS 

# include <pi:p/pu|)lil).h> 

// include <pup/pupconstants.h> 

1t include <pup/pupslatus.h> 

mlimeehcck(TimePort, GiYITinic) 
struct Port *TimePort; 
lpng *GMTimc; 

cc files ... -Ipup 
DESCRIPTION 

Mtinwchcck is used to find out what time a host thinks it is. This is done by making a TimeCheck 
request to the M iscSrrviccs server at the specified host. (Specifically, a "Now Standard Alto-style 
Time Check Request" is made.) 

The input parameter (passed by reference) is the Port address of the remote host. ( The socket field 
is ignored; time check requests are always directed to the MiscScrvices socket.) The host and net 
numbers can be zero, and the request will be broadcast to all hosts - only the first answer will be 
returned. In any case, the Port structure pointed 10 by the parameter will be set to the actual Port 
address of the responding server. The lime returned in GMTimc is the number of seconds since 
midnight, January 1, l ( )01, Greenwich Mean Time (( iMT). Note that this is different from the 
Unix base for time, which is midnight, January I, 1970. The function returns the value OK if all 
goes well. 

AUTHOR 

Jelfrey Mogul 

SEE ALSO 

miscservcr(9), timecheck( 1 m), timeconvert(9) 

DIAGNOSTICS 

There are several possible error returns: 

NOC.'HAN means that no Pup channels were available. 

I I M l 'OUT means that the server did not respond within a reasonable period. 

HUGS 

The MiscScrvices servers which properly implement this service return a lew more words, indicat- 
ing things like the local lime/one and the local period when Daylight Savings Time should be in 
elfect. Mtinurlhxk does not return these useful tidbits; Unix has essentially equivalent mechanisms 
anyway. 
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NAMft 

pupetaw — data structure describing a Pup channel 

SYNOPSIS 

7/ include <|)ii|)/jMij)iih.h> 

l)j;S(HH»HOiN 

A i'UjtCfMti is a data structure which is used to describe a Pup channel, over which Pup-based com- 
lMiaication may Ikw. The rw/r operations a user should e\er do on a PupChan arc (1) define 
space for it (e.g., struct PupChan ins than;), and i?) pass its address to the routines in the Pup pack- 
aye (e.iu pu|viosd&imchau); .) Any other reference to a PupChan is forbidden. PupChans, once 
opened, should not be deallocated until they are closed. 

AUTHORS 

John Seaiuons. Jclf Mogul, Dan Kolkowitz 

SfvK Al*SO 

pupopcn(')), pupelose(')), pupsetmodc(9), etc. 

bugs 

No enforcement mechanism exists to keep foolish programmers from abusing PupChans. 



7th lulilion 



\ 



PUPCI.0SK(9) 



UNIX Programmer's. Manual 



PUPCI.OSK(9) 



NAME 

pupclosc — close a pup channel 

SYNOPSIS 

# include <pnp/puplil).li> 

# include <pup/piipstatus.h> 

pupclose(Pclian) 

struct PupChan ♦Pchan; 

cc lilcs ... -Ipup 

DI SC RIP HON ; } 

Pupclosc is used to close a Pup channel opened by pupoprn( ( J). 

AUTHORS 

John Seamons, JelV Mogul, Dan Kolkowilz 

SKK ALSO 

pupopen(9) 

DIAGNOSTICS 

Normally, the return value is OK. However, if you try to close a Pup Channel that was not really 
open, you (probably) will gel PCNOTOPI-N. 
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NAMK 

\(p«|Hlcscrif») pup'nuleserip, piipoutdcsertp, ptipfidtoehari — access mapping between PupChans and' 
lids 

SYNOPSIS 

i)it;)i»(teserif)(^elta«) 
strtul PupOmti *pehan; 

paimiUOt'seni^jvehaH) 

struct t*tip<*tian *|Hi|ifMltt»cHan(fi(t) 
int Mi 

«• files ... -fpup 
!)i:s( KiruoiN 

for each open PupOran (as returned by impufcni*)}}. there \s one or nmre Unix file descriptor 
CTtd") associated. If a program uses the .v< A '</('» -system call in conjunction with Pup, it may need 
to lind out what the associated fid is for a PupChan. fmfMthfe.se rfp returns the lid associated with 
input on the specified PupChan. PitpoutJcscrip is provided lor completeness, bat is probably not 
useful. 

l ire typical use of the (tie descriptor is to create a mask for use with select. 

Also important for users' of select with multiple file descriptors (the usual case) is way to get at the 
inverse mapping; once you know that input is pending on a given fid. pupjhth>elnm returns a 
pointer to the Pupl'huR for which the fid is open. 

P'or example* 

long selttmsfc '=s 0; /* assuming no more than M fids */ 



pupopen(&pehan, sresocket, Efctfc 
sefmask f ----- ( l«pupindescrip(&pchan»; 



readfds - sclmask; 
serect(32. &readfds, 0, 0, f»; 
k#ti -• It readfds; t-t- + ) { 

if f( readltts & U«i» = - 0) continue; 

tvadfcis&^ 11 « i>; 

dump ~ pup{tdlochan<i); 

pupteadf chanp, ... ..); 



AUTHOR 

Jeff Mogul 
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SEK ALSO 

pupopcn(9), sclcct(2), puplisten(9) 
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NAMK 

PuplirrMsg — human readable error message from Tup package routines 

SYNOPSIS 

4t include <piip/|)U|)lil).li> 

ec files ... -lpup 

disc mrnoN 

Pupl'.rrMsy, is a globally deli nod character siring (hat is used to hold human-readable error mes- 
sages from routines in the Pup package. It is lor convenience only. 

All I HOWS 

■ Jelf Mogul t ! 

BU(JS 

The maximum si/.e of the error message is {MAXIM iPDA TAI.!\N - 1) bytes. 
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NAME 

pupgethost, pupgct.net - got host, net numbers oflocal end of pup channel 

SYNOPSIS 

pupgc(hosl(pchan) 
struct PupChan *pclian; 

puppet net(pelian) 

cc files ... -lpup 
DESCRIPTION 

Puptivihosi is passed a PupChan (as returned by pupopad*))), and returns the host number of the 
local machine, with respect to the network over which the channel is communicating. 

PupRclnct is passed a similar PupChan, and returns the network number of the network over which 
the channel is communicating 

Note that any given machine may be connected to several networks, and may have di lie rent host 
numbers on each network. 

AUTHORS 

John Seamons, Jell' Mogul. Dan Kolkowitz 

ski: also 

pupopen(9), pupgetporl(9) 

BUGS 
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NAMK 

(pupgctport) pupgetsreport, pupgctdstport - get address of local, remote ends of pup channel 

SYNOPSIS 

pupjjt'lsrcporKpchan, prt) 
struct PiipChnn *pchan; 
si met Port *pi t; 

pup;»ctilstpor((pch;m, pi t) 

cc Hies ... -Ipup 
DESCRIPTION 

Pupgetsreport is passed a PupChan (.is returned by pupu/>cn( K ))), and returns the Pup port address 
(net it host// socket) of the local end of the specified Pup channel. /'///>#< ttlsi 'port returns the address 
of the remote end. 

AUTHOR 

Jell' Mogul 

SKK ALSO 

pupopen(9), pupgeihosl(9) 
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NAME 

pupint, pupnoint - enable or disable interrupts for received Pup Packets 

SYNOPSIS 

# include <pnp/pnplih.li> 

pupinl(Pclian, signum, routine, uscrarg) 
struct PupOian *Pchan; 
inl signuin; 
void (*rouline)(); 
char *useiaiy; 

l)upiioiiit(Pchan) 

cc files ... —Ipup — Ijobs 
DESCRIPTION 

Pupint is used to enable the delivery of an interrupt to the user process when a packet arrives on 
the given Pup channel. This is used to avoid blocking on Pup reception, which is a problem in a 
duplex environment. 

This call, by its nature, is currently Unix-dependent. The parameter siyjutm is the number of a 
Unix signal which may be used in the process of delivering the interrupt. It is not a good idea to 
chose this number blindly; for example. Unix docs not allow a process to catch SKJKII.I.. A par- 
ticular signal should not be used elsewhere in the program, nor is it wise to use the same signal for 
two different Pup channels, since the signal number is what enables the code to differentiate 
between interrupts from different channels (unless you use a .vc/ir/(2).) 

When a packet arrives, the specified routine is invoked as if it were called w ith 
rouliiie(Pelian, userarj;); 

This allows the interrupt service routine to know which Pup channel is involved. The uscmrg 
parameter can provide additional information; it could point to a data structure of some sort. 

If the same routine is specified for more than one Pup channel, it should be written lecntrantly. 
I lowever, it will not be called recntrunlly lor more than one packet on any single Pup channel. 

i'upnoinl may be used to disable interrupts on a given Pup channel. 

One warning: the interrupt is triggered by the arrival of a packet for the specified channel; how- 
ever, it is delivered before it has been determined if the packet's checksum is good. Therefore, if 
you have set PCM..RCI IIK.'KSUM (using f>upscmu><ltV))). you will block if the received packet had 
a bad checksum and you call pupmnK 1 )). This can be avoided by selling I VM.JGN IJAI X'KS; in 
this case, the caller of pupmul will have to check the return status and throw away damaged pack- 
ets. 

SKI'. ALSO 

signalO), sigvcc(2) for symbolic definitions of signals, so that you will know which of them to 
avoid. 

AUTHOR 

Jeffrey Mogul 

DIAGNOSTICS 

None. However, if a signal number out of the range of legal Unix signals is specified, nothing is 
done. 
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BUGS 

This is highly Unix-dcpcndcnt: the Pup-lcvcl implementation should not be in terms of signals at 
all. However, since the underlying implementation (i.e., the Unix etherncl driver) uses signals, it is 
important to be able to specify what signals are used. Otherwise, an "automatic" choice of signal 
assignments might conflict with a user programs's used of one the limited set of Unix signals. 
Kxpecl thai the signal argument will he obsolelcd in the future. 

The wise programmer will prefer to use sclect(2)\ see pujuicscnp( K )) for hints on how to do this. 
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NAME 

puplistcn, puplistcnall - open Pup channels on all connected networks . 

SYNOPSIS 

# include <pup/puplib.h> 

# include <pup/pupslatus.h> 

puplistcn(actioii, LocalSockct) 

int (*action)(); 

unsigned long LocalSockct; 

puplistenall(actioii, LocalSockct) 

cc files ... -Ipup 

description 

Puplistcn is used to open a Pup channel (see pupclian('))) on each of the networks to which the 
local machine is connected. It is much like pupopcnW), but it does not take a destination 
specification, and instead of returning a single PupChan to the caller, it instead calls the action 
function, passing the open PupChans to it. I.e., the action function should he declared 

action(pchan) 

struct PupChan *pchan; 

Action will he called one or more times, and should do all of the option-setting that is usually done 
after a pnpopen. Space for the PupChans that puplistcn opens is allocated by >nulloc(}); if they are 
ever closed (with pupclosc( { ))). they should then be deallocated using y/erO). 

Puplistcnall is identical to puplistcn, except that if opens a reachable network in the Pup internet. It 
has a very specific and limited usefulness. 

Puplistcn and puplistcnall is intended for use in server programs. 

AUTHOR 

Jeff Mogul 

SKI'. ALSO 

pupopen(9), pupdescrip(9), pupreopen( 1 )) 

DIAGNOSTICS 

Returns OK if it succeeds; otherwise it returns NOCIIAN if no channels are available; returns 
NOKOUTI' if you can't get there from here; returns AltOKT if mullocO) fails. 

liven if it returns something other than OK, there may have been some PupChans successfully 
open; your code should keep (rack of this and close/free them if necessary. 

KUCS 

Depends upon the gatewayinfo server. If it cannot reach gatewayinfo via IPC, it will only open a 
channel for the default network. This could be fixed, but mostly by duplicating a lot of 
gateway info's code in this routine. 

Puplistcnall won't work if there are loo many Pup networks to have them all open at the same 
time. 
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NAME 

(pupmisc) gctlong, makclong, gcishort, makeshort, gctlliWord, gctl .oWord — miscellaneous Pup 
rou lines 

SYNOPSIS 

# include <pun/j)U|)lil).li> 

unsigned long getlong(xl) 
unsigned long xl; 

unsigned long makelong(xl) 

'unsigned short gctshort(xs) 
unsigned short xs; 

unsigned short makvshort(xs) 

unsigned short getlliWord(xl) 

unsigned short gelLoWord(xl) 

ec files ... -Ipup 
DESCRIPTION 

Some miscellaneous routines for the Pup package. Note that most of these are coded as macros; 
you'd better not try to take their address or pass them to other functions. 

Read hyicorda (9) before reading this. 

gctlong is the approved way of reading a 32-bit integer from a Pup data buffer or 

header. 

makelong is the approved way of creating a 3?. bit integer to be stored in a Pup data 

butler or header. 

gcishort is the approved way of reading a 16-bit integer from a Pup data bulla* or 

header. 

makeshort is the approved way of creating a 16-bit integer to be stored in a Pup data 

buffer or header. 

gctlliWord returns the most significant 16 bits of a longword as a short integer. 

gell.oWord returns the least significant 16 bits of a longword as a short integer. 

AUTHORS 

John Scamons, Jell' Mogul, Dan Kolkowit/., Bill Nowicki 

SKK A I, SO 

bytcorder(9) 

BUGS 



7th Hdition 



1 



PUPNKTTAIK9) 



UNIX Programmer's Manual 



PUPNKITAB(9) 



NAME 

(pupnettab) setpupnettab, getpupnettab, endpupnettab - pup configuration tabic 

SYNOPSIS 

# include <pup/puplib.h> 

struct pupnettab *gcipupncUab() 

int setpupnottabO 

int end pupn cttab() 

cc files ... -Ipup 
DESCRIPTION 

These routines arc used to find out the configuration of Pup network interfaces attached to the local 
host. 

Gclpupncllab returns a pointer to an object with the following structure containing the broken-out 
fields of a line in the Pup network description file, /ctc/pup/pupnettab. 

struct pupnettab { 

char *pnl„dcvnamc; 
struct Port pnt_addrcss; 

}; 

The meanings of the fields are: 

pnl_dcvnamc a string giving the "base name" of the interface special file. 

pnt_address gives the Pup network and host numbers of the interface (the socket field 

is zero.) l-ither of these fields may be zero, to indicate "unknown". 

Gclpupncllab reads the next line of the file, opening the file if necessary. 

Sclpupncfldh opens and rewinds the file. 

Kiulpuptu 'Hub closes the file. 

MLES 

/ctc/pup/pupnettab 
MIJ«: FORMAT 

Comment lines begin with '//' in first column. Other lines have 

(icviccnamc <white-spacc> net # host U 

Numbers arc in octal. Tor example, 

7/ Comment line 
/dcv/encla 50//327// 

The network number field is only important for those networks where a gateway is not present 
when gateway in jh starts. To be safe, you should gel this right: but getting it wrong won't be a 
disaster in most (not all) situations. 

The host number field is only important for lOmb networks, so that pup/Oarpser am know what the 
local host number is. 

The order of entries is important; the first entry is the one that will be used by default for name 
lookups and the like, and so should refer to the interface that is connected to the network best 
populated with server hosts. 
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DIAGNOSTICS 

Null pointer (0) returned on KOT or fatal error. Syntax errors on stdcrr. 

BUGS 

All information is contained in a static area so it must be copied if it is to be saved. 
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NAME 

pupopen - open a pup channel 

SYNOPSIS 

tt include <pup/puplil>.h> 
// include <pup/pup.slaliis.h> 

pupopt , n(Pchan 1 LocalSockct, KcmotcPorl) 
struct PupClum *Pclian; 
unsigned lonj; LocalSockct; 
struct Port *Renu)tcPort; 

ec files ... -lpup 
DESCRIPTION 

Pupopen is used to open a Pup channel (see pupelnm(O)) lo he used for I ml her Pup data transfers. 
The Rchun parameter is the address of a PupChan structure which will hold the stale of the chan- 
nel; the user is warned against meddling with this data structure. The I oeolSoekel parameter gives 
the socket on this host for the Pup channe : (the routine gets the source host and net address inter- 
nally.) The RcmotcRort parameter gives the nel/host/socket address for the other end of (he Pup 
channel; i.e.. the destination of packets sen! over the channel. Rupopen uses this information to 
establish routing and to chose a transport medium. If RemoicRort.net is zero, the underlying rout- 
ing code will choose some directly connected network; this probably make sense only for broad- 
casts. RcmotcRort may not be NUM. (this is change from previous implementations.) 

A channel opened with pupopen should be dosed with pupelo.sc( ( 0 . 

AUTHORS 

John Scamons, Jell' Mogul, Dan Kolkowilx 

sit; also 

pupclosc(9), pupread(')), pup\\rite(9), pupreopeu(9) 
DIAGNOSTICS 

Returns OK if it succeeds; otherwise it returns NOCIIAN if no channels are available; returns 
NOROUTI- if you can't gel there from here. 

BUGS 
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INAMK 

port - a data structure used in the Pup package, with support routines 

SYNOPSIS 

# include <|)ii|)/j)uplil).h> 
//include <sUlio.li> 

... wliicti defines ... 

struct Port { /* describes I lost // Net// Socket tuple */ 
I lost host; 
Net net; 
Socket socket; 

I; ; 

Port]-.()<PI,P2) 
struct Port *PI; 
struct Port *P2; 

l > ort( , oj))(lM..I > 2) 

PortPriimTI) 

I-Porl Printout, PI) 
I I I K H)ut; 

SPorlPrintduilTer, PI) 
char M)utler; 

Portl)ccodc(out, PI) 

PorlPack(tH\PP) 
struct Port UP; 
struct Packed Port PP; 

PortlJnpaek(IMM)P) 
ee files ... -Inup 

okscmpnon 

The Pari data structure is used to define the source or destination of a Pup packet. Note that the 
socket held is interpreted as a longword value, and that the actual packets may contain this sort of 
tiling in a dilfcrenl format. 

There are a variety of miscellaneous routines defined for manipulating Port structures; sonic are 
conveniences, but some are needed to provide machine-independence. 

PortHQ takes pointers to two Port structures, and returns true (non-/.cro) iff all 

three fields of both Ports are equal. 

PortCopy copies the Port structure pointed to by 1*1 to that pointed to by P2. 

PortPrint prints (on srdoul) the "standard" octal representation of the Port structure 

whose address is passed. Iv.g., one might see "50 //2(H)// 4" (the quotes arc 
not printed) for net = 50, host = 200, socket = 4. Note that no spaces 
are printed. 
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FPortPrint works like Port Prim but uses the specified stream instead of defaulting to 

si do i it. 

SPortPrint works like PortPritit but puts its output in the bull cr specified instead of 

printing it. 

PortDccodc prints on the specified stream a rendition of the Port, giving the net and 

host numbers in octal, but the socket number in a human-readable form if 
possible. F.g., the same example would print as "5()//20()//!VliscServices". 

Unfortunately, the Port structure cannot be used inside of Pup packets for two reasons. First, the C 
compiler throws in a gratuitous short word before the socket field, in an attempt to be efficient. 
Secondly, the order of the host and net fields (as well as the word order within the socket field) 
depends on the byte-ordering convention of the local host. Therefore, a structure called a Packed- 
Port is defined internally for use within packets; it should be considered to be a six-byte structure 
that must be short-aligned within a packet. It should only be manipulated with one of the follow- 
ing routines: 

PortPack packs the Port structure whose address is UP into the PaekedPort structure 

whose address is PP. 

PortUnpack unpacks the PaekedPort structure whose address is PP into the Port struc- 

ture whose address is UP. 

BUGS 

The type definitions for Host. Net, and Socket are (all unsigned) char, char, and long, respectively. 
This should be made more well-known. 
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NAIY1K 

(pupprinf) PupPrint, Print l-TrorPUP, Pupl ypcNamc - printing routines lor Pup 

SYNOPSIS 

# include <stdio.h> 

ft include <pup/puplib.h> 

# include <p«p/puptanstiuilsJi> 

PupPiint{out, toifler, length, ITintData) 
HIT. *oirt; 
ch;ir*l>uflVr; 
iht length; 

hit Print Data; ; « 

IViiitr.rrorfniPdHit. buffer, length) 

char *Puj)'lypeNanie{puptype, dslsoeket, sresocket) 
unsigned char puptjpe; 
unsigned long ds (socket; 
unsigned long; sresocket; 

ce files ... Tpup 
DESCRIPTION 

These routines are useful in debugging l^p programs, and providing low-level monitoring. 

PupPrint The buller (and buffer length) passed to this routine should be an entire 

Pup packet. A formatted rendition of the Pup will be printed on the 
stream specified by out. If f*nnffhfhi is rum -zero, the entire data segment 
of the packet will be printed. 

PrintllrrorPUP The bulVer (and bulfer length) passed to this routine should be the data 

portion of an I'KRORPUP packet. A formatted rendition of the larorPup 
will be printed on the stream ■ specified by ottl. 

Pup'I'ypeName Tries to figure Out a hitman -readable name for the given Pup type, based 

on the speciiied source and destination sockets. The name is returned in a 
static string. 

AUTHORS 

Jeffrey Mogul, Bill Nowicki 

SEE ALSO 

pupport(9) 

BUGS 

None of these are perfect. 
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NAME 

puprcad -- read a pup packet from a pup channel 

SYNOPSIS 

7/ include <pup/()uplil).li> 

# include <pup/pupconstants.h> 

// include <pup/pupstalus.h> 

pupread(Pchan, buf, Imflcn, Ptypc, II), DstPort, SrcPort) 

struct PupC'luiu *Pchan; 

char *buf; 

inl *buflen; 

unsigned char * Ptypc; 

unsigned long *ll); 

struct Port * DstPort; 

struct Port *SrcPorl; 

cc files ... -Ipup 
DKSCKIfTION 

Puprcad is used to read a pup packet from a pup channel (see pupclum( 1 )) .) The parameters are: 

The address of a PupChan structure as initialized by pupopcn( 1 )). A 
timeout and a packet filter should already have been set for this '.channel 
using pupsi'llimvouiVO and pupselfiltciCO. 

The address of a buffer to receive the data portion of the Pup packet. The 
bulfer should be large enough to hold the largest possible Pup data packet, 
which is normally no more than 5.V. bytes (MAXPUPI)ATAI.HN). You 
should no/ expect that the bytes in the buller whose indices are greater 
than the length specified by bujlcu are not modified by puprcad If this 
parameter is NUM., it is ignored (no data is returned.) 

The address of an integer which will receive the length (in bytes) of the 
data portion of the pup packet. If this parameter is NUM ., it is ignored 
(no data is returned.) 

The address of an unsigned char which will receive the Pup Type of the 
packet. If this parameter is NUI.I , it is ignored (no data is returned.) 

The address of an unsigned long which will receive the Pupil) of the 
packet. If this parameter is NUI .I ., it is ignored (no data is returned.) 

The address of a Port structure (see pori( l >)) which will receive the host 
number, network number, and socket to which the pup packet was 
addressed. This is useful for packets received which may need to be distri- 
buted among several sockets, and for gateway purposes. If this parameter 
is NULL, il is ignored (no data is returned.) 

The address of a Port structure which will receive the host/net/socket 
address of the sender of the Pup packet. If this parameter is NUM., it is 
ignored (no data is returned.) Unless PCM_WAN TOSRC is set in the 
channel mode for Pc/ian. puprcad will replace a zero network number in 
this structure with the number of the network it is recicved on. 

AUTHORS 

John Seamons, Jeff Mogul, Dan Kolkowitz 



Pchan 
buf 

bulled 

Ptypc 
II) 

DstPort 
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SKK AI SO 

piipopen(9), pupcU>se(9), pupread(9), port(9), pupchan{9) 

diagnostics 

Pupfcuil can return OK if things went tight, TIMHOUT if no packet was received during the 
channel's timeout period, and DADCKSUM if the Pup checksum was detected as being bad. 

The data locations referenced by the parameters will he modified only if (1) the return value is OK, 
or {2) the return value is BAI X.'KSUM, umi the channel mode for Pc/ian contains the 
PCM...K jNHADCKS attribute. This allows programs that would like to receive even d.imaged 
packets to do so. 

HUGS 

By „e swapping is problematical. 
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NAME 

puprcopen - change the destination for a Pup channel 

SYNOPSIS 

7/ include <pup/puplil).h> 
•// include <piip/pupsl:Uus.h> 

piiprcopenC l*cli:iii, DstPort) 
struct PupChaii *Pchan; 
struct Port *l)stPort; 

cc files ... -I pup 
DESCRIPTION 

Puprcopen is used to change the destination lor an open Pup channel (see pupc/ianp))). The 
DstPort parameter gives the new net/host/: oeket address lor the remote end of the Pup channel. 
Puprcopen uses this information to estahlish routing and to chose a trans|"»ort medium. 

AU i llOKS 

JelV Mogul 

SEE ALSO 

pupopen(9), puplislen(9) 

DIAGNOSTICS 

Returns PCNOTOPKN if the PupChan isn't already open, or if it closes the channel and cannot 
reopen it; returns NOC.'IIAN if no channels are available; returns NOROUIT. if you can't gel there 
from here: otherwise, it returns OK. 

BU(kS 
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IN A ME 

puproule find a route for a Pup Internet packet 

SYNOPSIS 

ft include <|)ij|)/pti[)lil).h> 

// include <|)up/|)u|)eon.slants.li> 

# include <pu|)/pupst;itus.h> 

pit protitc{i)cst Port, Vial lost, ViaNet, DeviName, DevNanieLen) 

struct l»orl *l)esil , ort; 

I lost * Via I lost; 

Net *VialNet; 

char * DeviName; 

int DevNameliCii; 

cc files ... Tpup 

i)i:s( KiiM ioN 

Pupivutc is used to find a route through the Pup internet to the specified deslinalion port 
(net/hosl/soekel iiddress). It returns (in the reference parameters Viallosl and VUiNct) the first hop 
host address and net that should he used lo reach the destination. Vhillost is cither the Pup host 
number of the destination, if it is on a directly-connected network, or the Pup host number of the 
fust gateway along the route. Y'iuNct is used to determine which directly connected net should be 
used, if there are more than one. If either I'ial/osiar !7</.V<7 is NUM., it is ignored. 

I'uphjulf also returns in the buffer addressed by /)cv\'unic the name of the de\ice to be opened 
(i.e.. the interface to J'w.VW): DnNdmcf cn should be the size of this butler in bytes. 

If l)csift)it.in't is zero, then pupmuiv will choose an arbitrary connected network; this is useful, for 
example, when the "destination" is a nameservcr on whatever network is available. 

Note that pupmutii) is normally called only by pui>opcn( { )), and should not be seen at higher levels. 

ski-: AI SO 

pupopen(V). puprouting(9) ' 

DIAGNOSTICS 

Normally returns OK; returns NOROUTIi if a route cannot be found. 

AUTHOR 

Jeffrey Mogul <f? Stanford 

ihjc;s 

There are two versions of this routine; one uses Unix IPC to try to ask the xatcwayitifoV)) server for 
a route; if this fails, it proceeds lo go out over the network to find a gateway. The routing tabic is 
constructed once (the first lime il is needed) and if the fust table received from the internet is 
deficient, or if the internet connectivity changes during the lifetime of the process, nasty things may 
happen. 
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NAME 

pup routing - Pup Internet routing tabic maintenance routines 

SYNOPSIS 

# include <pup/puplil).li> 

# include <jmp/pupconstants.h> 
// include <pup/pupstatus.h> 
//include <pup/puprouU\h> 

Init touting! 'al)le(devname) 
char *devnamc; 

llpdateRoutiiij- rabMCWIPupData, GWIl.en, (iWport) 

char KiWIPupData; 

iut GVVILen; 

struct Port *(i\Vport; 

PurgeRoutingTablcO 

Print RoutingTnbleO 

extern struct PupRouteKiitry l > ui>Koiiliiig'l':il>It>|iMAX.I > Ul > NK'l'Sl: 

cc files ... -Ipup 
DIuSCKlPI'ION 

The routines described here are used to maintain the tabic used for determining internet routes for 
Pup packets. They arc not normally seen by code outside the pup library (except perhaps in gate- 
way servers), but they are being described for posterity's sake. 

A routing table contains entries of type I'upRoutcf-'mry, delined in <pup/puproutc.h>. 

struct PupRouteKiitry { 

Net TargetNct; /* net for which route is given */ 
Net d'atcwayNcl; /* network number lor lirst gateway */ 
Most (ialewayllost; /* host number Tor lirst gateway */ 
uchar I lopCount; /* hops to TargctNcl */ 
long Update rime; /* time this entry was last updated */ 

} 

Note that the local host is effectively a gateway to its directly connected networks, those with a 
hop-count of zero. If the hop count is zero, then the proper action is to send packets directly to the 
target host; otherwise, they should be sent to (itilcwuyltos/ via (ititcwayNct. 

There is a globally delined routing tabic PnpRoulingTable. 

KOUTINKS 

The routines which modify an existing routing table ( VpMUt'RoulinyJ'ablc and PwncRouliii^Tablc) 
return true (nonzero) ijf i\ "real change" is made to the table, one that should be propagated to 
other hosts. 

InilRoulingTnblc This is a simple routine which requests a routing table by broad- 

casting a "Gateway Information Request" and taking the first 
reply. This is not perfect, but it's as good as can be done if we 
cannot asynchronously listen for broadcasts. The dcvmmie param- 
eter specifies which network interface to use; if multiple interfaces 
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UpdalcRoutingTable 



PurgeRoulingTable 



PrintRoutingTable 



exist, ill is routine can be called in sequence on each one to create 
the most accurate routing table. 

This lakes the Pup data buffer from a "Gateway Information 
Reply" Pup, as specified by (/IV/ftipfhifa and CrlVfl.cn, and the 
Pup source address of this dala, (tlVporl, and updates the 
specified routing table. The algorithm used is defined by the 
Xerox meinonindum on the Gateway Information Protocol cited 
below. 

This should be called for a routing table periodically (on the order 
of once every 15 seconds or so), it removes entries that arc too 
old to be considered valid, also, according to the algorithm given 
in the Xerox memorandum. 

'1'his is used in debugging; it prints the given routing table on 
shh'Hl in a human readable format. 



SKK ALSO 

pupopen{9), puprouteO)), [I iissenj<Pup>Galeway Information. Press 

DIAGNOSTICS 

None. 

AUTHOR 

Jeffrey Mogul (</ Stanford 

BUGS 
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NAME 

pupsctbacklog - set input queue backlog for pup channel 

SYNOPSIS 

# include < p u p/p 1 1 p 1 i b.h > 

pupsolhacklo^Pcliun, backlog) 
struct PupClian *Pchan; 
inl backlog; 

cc files ... -lpup 
DESCRIPTION 

hipsellkickhn sols the input backlog for the given Pup channel. The backlog value specifies the 
maximum number of packets that will be queued in the kernel pending a read system call. 

If backlog is zero, a default value will be used, and if it is larger than the maximum alloablc value, 
the maximum will be used. 

AUTHORS 

JelV Mogul 

SEE ALSO 

pupopen(9) 
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NAME 

ptipsetdfilt - set a default packet filter fm* a Pup channel 

SYNOPSIS 

#i|aiudc <pii|j/pfi|5lih.Ji> 

# inchide <f)U|)/(Hipcous{ants.li> 

# include; <pup/pupstatus.lj> 

pupseldJil*^N:hau,prtority) 
struct J *npOiau *l*e}ia«; 
uns ijyied dm priority; 

ce files ... -Ipup 
DESCRIPTION 

Pvpscuifiti sets a packet filter Tor the given Pup channel. A packet filler is a mechanism for specify- 
ing which packets should he delivered to your Pup channel. Piipxcftlji/f decides, on the basis of the 
Pup channels mode, what fields of incoming pup packets should he checked for equality against 
given values, and if the packet matches aU of the specified values, then puprcaJW) will deliver it to 
you. Otherwise, it will be checked against the packet filters for other Pup channels anil processes. 

The routine is given the address of a Pup channel structure, and a priority for the filler. Higher 
priority filters will be checked first, in case more !han one lito accepts a packet. 

Normally, the filter created will check the destination socket field of the incoming packet, and if the 
channel mode (see piipsvimodcW)) does not include JtjMJtiKOAl X'AST, the destination host field 
as well. 

If you want more control over the filter, use pujm*40iM%> 

AUTHORS 

J cIV Mogul 

SM ALSO 

pupselfilter(9), pupopeu(9) 

diagnostics 

Normally, this should return OK. However, it is possible thai it might return P'lL'l l vR TO0IHCJ if 
something about the implementat ion of filters cliauges djaslkally. 

BUGS 
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NAME 

pupsctfiltcr - sot tlic packet filter for a Pup channel 

SYNOPSIS 

# include <pii:./puplib.li> 

7/ include <pu<)/pupconstunts.h> 

# include <pup/|)upslatus.h> 

pupsctfiUer{Pclian,piiority,l , puj)type l Fpupid^<lstiietJ'Usthost,Pdslsock, Fsrcnet,Fsrchost,Fsrcsock) 

struct PupChan *Pchan; 

unsigned char priority; 

unsigned char *l'puptype; 

unsigned long *Lpupid; 

unsigned char *!'dstnet; 

unsigned char *Fdslhost; 

unsigned long ♦Fdstsock; 

unsigned char ♦ Lsrcnct; 

unsigned char * Fsrehost; 

unsigned long *l\srcsock; 

cc files ... -Ipup 
DESCMPHON 

PupsclJUler sets a packet filter for ihc given Pup channel. A packet filter is a mechanism for speci- 
fying which packets should he delivered to your Pup channel. Pupscljillcr allows you to specify 
certain fields of pup packets to be checked for equality against given values, and if the packet 
matches all of the specified values, then puptvad^)) will deliver it to you. Otherwise, it will be 
checked against the packet fillers for other Pup channels and processes. 

The routine is always given the address of a Pup channel structure, and a priority for the filter. 
Higher priority fillers will be checked first, in case more than one filter accepts a packet. The rest 
of the parameters are optional, in the sense that you can either give the address of a value for the 
filler to check, or NULL. II' the parameter is null, the filter will ignore the associated field of the 
incoming packet. 

The parameters are associated with, respectively, the packets Pup Type, Pup Id, Pup Source 
net/host/socket, and Pup Destination nct/host/sockct. 

If this seems too complex, look at pupscldjilli 1 )), which tries to figure out what filter you really want. 

AUTHORS 

JelT Mogul 

SEE ALSO 

pupsetdlill(°0, pupopen( ( )) 

DIAGNOSTICS 

Normally, this should return OK. However, it is possible that it might return I 'ILTIUl TOOHIG if 
you try to specify too many fields to check. In the current implementation, you should be able to 
specify all of the fields. 

BUGS 
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NAME 

pupsetmode,, pspgetoiode — set- and read Hie .mode' for a Pup channel 

SYNOPSIS 

# include <p«p/^{iiii*lib.Ii> 

struct Pup( han *i*cltan; 
short mode;.. 

short puppet nitxteC I Vhan) 

cc Irks -Ipnp 
DESCRIPTION 

Pup channels (see pupelntnW)) can have a number of attributes that are used to control activity' over 
the channel Colleetiuiy. the attributes of a channel are known as Its. muck. ftt>):;vtnunh' and pup- 
gcMmk arc used to set and read the channel mode. 

Available modes are: 

PCM J<t:i ll-CKSUM Check the Pup checksums of packets when reading them.'. IT this attribute 

is not set, the checksum is always ignored. 

PCM_WCt IKCICSUM Insert a checksum into the Pup pickets when writing them. If this attri- 
bute is not set insert a constant which means "this packet has no check- 
sum." 

PCktJIROAIX'AST If this attribute is set pupsrkljSfft) will insure that packets directed to host 
0 (broadcast pickets) are not received. Otherwise, packets directed to 
either the hn^tt host, or to host fl, will be received. 

PCyjGNBAIXKS Setting this causes ; pttpn-mfflX -.to ignore bad Pup checksums. Otherwise, 

puprt'tutW)> will ntrt after any of 'its. reference parameters if the checksum is 
bad and if IV&f RCIII-cksMM is set. 

PClVL W AINf I'WKRC Setting this causes pttpmhH*)} to return the Pup Source port of a received 

packet, without modifying it. By default, pttprmJ will try to ensure a non- 
zero tret number in the Pup Source ports it hands hack to the caller. 

For convenience, sy mbols arc defined tor the dear state of each attribute; e.g., the clear state o f 
PCM l*Cl IfcCK&UM is E "CM NOR CI H :C K SUM. I-aeh attribute is encoded as one bit; therefore, 
multiple attributes should be or'ed together to form a channel mode. Note that the default mode is 
all attributes in the clear state. 

AUTHORS 

JetT Mogul 

SKK /VI. SO 

pupreadC**). rmpwritd^k pupsetdlitiPJ), pupopen(9). pu|K.han(9> 
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NAME 

piipsctlimcout - set timeout for pup channel 

SYNOPSIS 

// include <|)i)j)/|)iiplil).h> 

puj>settiincoiii( I Vluui, timeout) 
struct PupChan *Pclian; 
iut timeout; 

cc files ... -Ipup 
DESCRIPTION 

Seltinwoul sets the read timeout lor the given Pup channel. The timeout value is (currently) in 
clock licks (1/00 second). The constant ONI-SI-C may be used as a one second timeout, and is 
likely to he transportable. 

AUTHORS 

Jell* Mogul, Dan Kolkowilz 

SEE ALSO 

pupopen(9) 

bu(;s 

'The 1/fiOth timeout quantum may not be, loo transportable. 

The Vax implementation has a maximum timeout of about IS minutes. Any larger value will pro- 
duce unpredictable results. 
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NAME 

(pupslring) GclHCPI siring, PutlKTI string, CictMesastring, PutMesaslring - manipulate strings 

SYNOPSIS 

7/ include <pii|)/|)ii|)Iil).lt> 

unsigned short (;cll\h.sasliing(froin,to) 
struct ftli'saStriiig *lrom; 
char *lo* 

Gel IK IN .Siring from,! <>) 
struct IU'1'1, siring *from; 
char *to; 

IVitfiCIM Strin^froin, to) 
char *from; 

struct ll(TI.-striilj> *lo; 

cc lilcs ... -Ipup 
DESCRIPTION 

1*11 p objects often contain text strings in formats peculiar to either Mesa or IJCPI . These routines 
allow you to convert them to and from (' strings (null terminated arrays of char). 

Read V.n 7/ •< //•</*'/•( 9) before reading this. These routines are meant for dealing with Mesa or BCPI. 
strings inside of packets, and C strings outside of packets. 

GetlK.PI string takes die address of a IK. PI string (don't worry about what this structure 

looks like, just pass the address of what you think is a IK. PI string), 
extracts it into a (' string (null terminated, of course), and returns the 
length in bytes of the liCPI String structure that you gave it (not the 
length that strlen(lo) would return.) This value is useful if you have a lot 
of IK. PI strings packed together. 

PutiK.'PI string moves a C string into a IK 'IM string; and returns the length in bytes of the 

IK'PI string object. The buffer whose address you pass lor the to argu- 
ment should be longer than the C siring by a few (i.e., at least 4) bytes. 

GelMesasliing takes the address of a MesaString (don't worry about what this structure 

looks like, just pass the address of what you think is a MesaString), 
extracts it into a C string (null-terminated, of course), and returns the 
length in bytes of the MesaString structure that you gave it. I bis value is 
Useful if you have a lot of MesaSlrings packed together. 

Put Mesastring To be specified. 

AUTHORS 

John Seamons, Jeff Mogul, Dan Kolkowitz, Hill Nowicki 

SKK ALSO 

byteorder(9) 

BUGS 

VuthtcsaStiiii& isn't implemented. 



7th I'dition 



1 



PUPWKI I I-.(9) 



UNIX Programmer's Manual 



PUPWRITK(9) 



IMAMK 

pupwiitc — write a packet to a pup channel 

SYNOPSIS 

# include <pt!p/pnplii>.li> 

include <pup/pupconslants.h> 
// include <pii{)/pupstatus.h> 

pupwTite(Pclian, Ptypc, II), biif, buflen) 
struct Chan *Pehan; 
unsigned char Plype; 
unsigned lou« II); 

char *huf; 1 ! 

hit ha lien; 

cc files ... -Ipiip 
DKSCUIPTION 

hi/mrifc is used to send a Pup packet over a pup channel opened using pupopcn(l). The parame- 
ters are: 



Pchan 'The address of a Pup channel (as initialized by pupopcn(9)), over which 

the pup packet should he sent. 

Ptype The PupType lor the packet to be sent. Registered Pup types are defined 

in <ptip/pupconstants.h>. 

II) The Pup II) for the packet to he sent. 

buf The address of the data to be sent. 

bullen The number of bytes to send. 



Pullers should always have an even number of bytes allocated, even if the huflcn parameter is odd, 
since pupwriic will round up the hulVer length to an even number before copying it into the packet. 
This eon forms lo Pup specifications, which state that packets must contain a garbage byte if neces- 
sary, to make the packet an even length. 

AUTHORS 

John Seamons, Jell" Mogul, Dan Kolkowitz 
SKE ALSO 

pupopcn(9), pupclosc(9), pupread(9), porl(9), pupchan(9) 

DIAGNOSTICS 

Returns OK if things went right. 

huc;s 
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NAMK 

ringbuf - ring bullcr package 

SYNOPSIS 

// include <i>tip/rifi}*f>iif.li> 

si met ningUuf rngbuf; 

rnglHiliuii{&ingl>uf, tlahiluif, maxhuflcii) 
char *4!;t(al»uf; 
in! ihaxluiilcn; 

iiil mglHdsi/e(<&mglHil) 

rn j^hti lp 11 1 ( & I'li^htif, c) 
chare; 

char rii^htilj'cti&rnghu!) 

rM£l)ufwrik'(&m«hur, iiipulhuf. Ion) 
char Mn put Imf; 
hit ion; 

rnf;l>ulro:u!(.!?:in$>l>uf, output huf. Ion) 
char +ou!|>utlMif; 
I ii 1 leu; 

nigbufpeeM&riigbuf, outpulbiif, leu) 
cc files ... -Ipup 

disc KirnoiN 

I ho ring bullcr package was written to provide a general purpose, high speed ring bullcr facility for 
use in network software. The object code is part of the pup library lihpup. A ring bullcr provides 
lirsl-in, lirsl out. bullering, in this ease ol" bytes. The bullcr space itself is provided by the user, and 
thus may be. of any convenient si/e. However, one must not provide less bullcr space than one 
intends to use; this package normally perforins no consistency checks (to keep efficiency high), and 
will gladly trash all of your data without complaining, j'l he package can be compile to print warn- 
ing messages ori overflow or underflow, for debugging purposes.] Routines are provided for cither 
byte-by-byte transfers, or block transfers, ami use of these two modes may be intermixed at will. 

The ring buffer must be initialized once by calling niybutinU with the address of a Hinglhtf struc- 
ture, the address of a data bullcr, and the maximum number of bytes that the buffer can hold. 
After initialization, this data bullcr should not be referenced directly, and of course it cannot be 
deallocated until no further use is contemplated. 

It is ollen useful to know the number of bytes contained in the ring bullcr, especially in order to 
avoid overflow or undcrllow. The function mghufst'zc returns the number of available byte of data 
in a given ring buffer. 

To insert bytes into a ring bullcr, either rnglmfput or myjmfwrite may be used. Rnyhufpul adds one 
byte to the ring bullcr; rnyhufwriiv lakes the address of a data bullcr, and the length of the data 
buffer, and copies this data into the ring bullcr. [Horrible things will happen if this overflows the 
available buffer spacc!| 
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To retrieve bytes from a ring buffer, either mghufgvt or rngbufread ' may be used. Rnghufgel is a 
function that returns one byte from the ring buffer; niyjnifrcthl takes the address of a data buffer, 
and the number of bytes to read, and copies the requested information from the ring buffer to this 
data bullcr. 

Both rngbufget and mgbufrcud do destructive reads; that is, any data that they return is removed 
from the ring bullcr. Sometimes it is necessary to find out what would be the next data returned 
from the bullcr without actually removing it from the bullcr; in order to make this possible, niyjmf- 
peek works exactly like niyj>uj'n\ul, except that it does not remove the data from the bullcr. 

CAUTIONS 

If the ring bullcr ever underflow's or overflows, it is unlikely that any future operations will work 
properly. Moreover, your program may crash mysteriously! 

Any or all of these functions and procedures may be re-implemented as macros or in assembly 
code for clllciency; thus, it is unwise to write programs that would be affected by one or both of 
these re implementations 

SKK A I SO 

mallocO) 

DIAGNOSTICS 

If compiled with the symbol DlililKj defined, lh<\sc routines can print warning messages on the 
standard error stream- Qtlierw isc, (lia|jiu'^lics-Wi i c<n(Jl-jp.rt)viilcd. 

AUTNOK 

Jeffrey Mogul 

HUGS 
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NAIY1K 

UAtimecvt - coitvcrsions from Unix to Alio tittieand vice versa 

SYNOPSIS 

# include <pup/UAtiniccvtJi> 

\toUtiiui{clock) 
UtoUime(cloek) 

()KS( Kin iON 

Moil time and tltoAtinic arc used to convert internal time formats between Unix and Alto systems. 
/Both systems keep time as the number of seconds since midnight, January I. (!MT, of some year. 
The dilVerence is that Unix starts from \ K )70. whereas Alios start from \%)\. (Note that midnight 
starts a new day, so the time at noon on January I, 1901 is positive, on an Alto.) Intervening 
leapyears are taken into account as well. 

A ml flinir converts a longword representing an Alto internal lime to a longword representing the 
corivspondiug Unix internal lime. / 'toAtimc does .the complementary conversion.. Make sure you 
use longwords! 

Be warned thai these are macros. 

AUTHOR 

Jeffrey Mogul 

sit: also 

timet A), eiimeU) 
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NAME 



UniqueSockct create unique socket number 



SYNOPSIS 

unsigned Ion;; IJniqticSockclO 

cc files ... -Ipup 
DESCRIPTION 

UniilucSockct is a function that returns a number which is guaranteed to be unique during the 
current incarnation of the operating system. Uniqueness is guaranteed neither across crashes, nor 
across hosts, although using a combination of this number and the limc-of-ycar returned by fim< (2) 
should gi\e reasonable results. 

The value returned is useful lor creating unique sockets, connection ids, etc. In particular, it is 
guaranteed not to be the same as any "well-known" Pup socket. 

AUTHORS 

Jell' Mogul 

BUGS 

The "guarantee" of uniqueness is only probabilistic^ correct (it gets worse as the product of pro- 
cess creation rate and average connection lifetime goes up), and does not hold if a single process 
manages to call the function more than 255 times during one clock Lick. In practice, though, it 
should work well enough. 

The MC68000 implementation is even worse; there is a global variable which is incremented on 
each call. This will stop working when there .ire multiple processes involved. 
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